home *** CD-ROM | disk | FTP | other *** search
/ Aminet 28 / Aminet 28 (1998)(GTI - Schatztruhe)[!][Dec 1998].iso / Aminet / dev / c / AMesaRTL.lha / Mesa-2.6 / amiga / README.AMIGA < prev   
Text File  |  1998-09-19  |  13KB  |  342 lines
  1.  
  2.                              AmigaMesaRTL 2.0
  3.                       A run-time library of Mesa 2.6
  4.  
  5.                          by Jarno van der Linden
  6.                             jarno@kcbbs.gen.nz
  7.  
  8.             http://www.kcbbs.gen.nz/~jarno/AmigaMesaRTL.html
  9.  
  10.              Mesa 2.6 is Copyright (C) 1995-1998  Brian Paul
  11.  
  12.  
  13.  
  14. INTRODUCTION
  15. ============
  16.  
  17. Once upon a time there was an Amiga port of Mesa by Stefan Zivkovic.
  18. However, just as this port became interesting, Stefan could no longer
  19. support it.
  20.  
  21. Then came CyberGL. A run-time library, which ran reasonably comfortably
  22. even on lower-end machines with AGA. Unfortunately, it only implemented a
  23. subset of OpenGL. Furthermore, the output even on a 256 colour AGA screen
  24. was far from impressive. At present, development seems to have stalled
  25. (possibly pending the release of the 3D drivers for the CV-PPC and BVision
  26. cards).
  27.  
  28. Back to Mesa, through H&P we've seen the release of StormMesa.
  29. Unfortunately this too comes in the form of a link library. (Although that
  30. is soon to change I gather).
  31.  
  32. So I set out to create my own driver with the following objectives:
  33.  
  34.     - Based on the latest release of Mesa
  35.     - Should come in the form of a run-time library
  36.     - Reasonable speed on an 50MHz '030/'881 system
  37.     - Good quality output on AGA
  38.  
  39. With AmigaMesaRTL, I think I have achieved these goals. Of course, don't
  40. expect miracles. Framerates are still better counted in seconds-per-frame
  41. rather than frames-per-second on my machine (A1200, Blizzard1230IV, 50MHz
  42. '030/'881, 32MB fast). But it is still faster than CyberGL and the output
  43. is a significantly better.
  44.  
  45.  
  46.  
  47. THEORY OF OPERATION
  48. ===================
  49.  
  50. The main Mesa functions (such as glBegin(), glFlush(), etc. etc. etc.) are
  51. in mesamain.library. These functions do all sorts of things, and
  52. eventually call some driver functions to handle the platform-specific
  53. output.
  54.  
  55. The driver (amigamesertl.c) does all reading from and writing to a simple
  56. memory buffer. This buffer is made up out of single bytes in the case of
  57. colour index mode, and 4 bytes in the case RGB or RGBA mode.
  58.  
  59. When glFlush() is called, the buffer is processed by an Output Handler.
  60. The traditional thing for an output handler to do is to quantize the
  61. buffer to a displayable number of colours, and C2P the buffer to a window.
  62. Output handlers can however do many other things, such as send the buffer
  63. directly to an image editing program (e.g. ImageFX using the
  64. magic.library).
  65.  
  66. What output handler to use depends on the output type specified by the
  67. application. For example, if the output type is "Window", the output
  68. handler specified by the environment variable "AmigaMesaRTL/Window" is
  69. used.
  70.  
  71. The default output handler is a slightly modified version of DL1 from a
  72. package by Dennis Lee (denlee@ecf.utoronto.ca). I've included the original
  73. documentation in the amiga/outputhandlers/dl1 directory.
  74.  
  75. Because of the various buffers involved, AmigaMesaRTL does use a fair bit
  76. of memory.
  77.  
  78.  
  79.  
  80. COMPILING THE LIBRARY
  81. =====================
  82.  
  83. The AmigaMesaRTL distribution only contains the changed and new files of
  84. Mesa. You will need the Mesa 2.6 distribution. Once you have obtained the
  85. Mesa 2.6 distribution and unpacked it to somewhere, copy the amiga
  86. directory of AmigaMesaRTL to the Mesa directory. Go to the amiga/src
  87. directory, change the SCOPTIONS file to suit your system (mainly the MATH
  88. and CPU settings), and run SMake. Sit back, relax, enjoy life. This is
  89. going to take a while.
  90.  
  91. Note that there are still a few references to __XCEXIT(). Just ignore it
  92. and let the linker replace it with __stub().
  93.  
  94. Once this is done, you should end up with a file called mesamain.library
  95. in the amiga/library directory.
  96.  
  97. Go to the amiga/drivers/amigamesartl directory, edit SCOPTIONS, run SMake.
  98. Out pops amiga/mesadrivers/amigamesartl (no ".library").
  99.  
  100. Some output handlers can be found in amiga/outputhandlers. Go to one of
  101. them (e.g. dl1), edit SCOPTIONS, run SMake, and you should now have a
  102. library called amiga/library/outputhandlers/dl1.
  103.  
  104. The GLUT library is made by going to amiga/src-glut, edit SCOPTIONS,
  105. SMake, and you have amiga/library/glut.library.
  106.  
  107. Finally, go to the amiga/lib directory, edit the SCOPTIONS file if you
  108. want to, run SMake. Out should come Mesa.LIB and GLUT.LIB.
  109.  
  110. That is all that is needed to get a working mesa library. Whew!
  111. Alternatively, edit all the SCOPTIONS files you can find to suit your
  112. system and execute mklib.amiga.
  113.  
  114.  
  115.  
  116. USING THE LIBRARY
  117. =================
  118.  
  119. To compile a program using AmigaMesaRTL, make sure the compiler can see
  120. the files in amiga/include and the link libraries in amiga/lib (by e.g.
  121. adding them to your INCLUDE: tree).
  122.  
  123. Mesa.LIB contains autoopen code for the mesamain.library, so you shouldn't
  124. have to worry about opening and closing it. Just don't forget to link with
  125. Mesa.LIB. It will also cause a driver library to open.
  126.  
  127. If you want to open the libraries yourself, I recommend opening
  128. mesamain.library, and then getting a driver library base from it by
  129. calling mesaGetAttr(MESA_DriverBase,&mesadriverBase). It is also possible
  130. to open a specific driver, see the mesadriver and mesamain docs.
  131.  
  132. In typical use, you probably want to output the result to a window. After
  133. setting up your Intuition window as per usual, create a context for it by
  134. calling AmigaMesaRTLCreateContext(). Pass a pointer to the window to the
  135. output handler with OH_Output, and tell it is a window by setting
  136. OH_OutputType to "Window". Make sure the context is current by calling
  137. AmigaMesaRTLMakeCurrent().
  138.  
  139. Do lots of interesting graphics stuff. Don't forget that glFlush() has to
  140. be called (directly or indirectly) for the result to be send to an output
  141. handler.
  142.  
  143. Before closing the window, you should destroy the context with
  144. AmigaMesaRTLDestroyContext().
  145.  
  146. For example (without error checking):
  147.  
  148.   my_window = OpenWindowTags(...);
  149.   my_context = AmigaMesaRTLCreateContext(
  150.                      OH_OutputType,  "Window,    /* Output is a window */
  151.                      OH_Output,      my_window,  /* Use my window */
  152.                      AMRTL_RGBAMode, TRUE,       /* RGBA drawing mode */
  153.                      TAG_END);
  154.   AmigaMesaRTLMakeCurrent(my_context);
  155.  
  156.   /* ...Do OpenGL stuff... */
  157.  
  158.   AmigaMesaRTLDestroyContext(my_context);
  159.   CloseWindow(my_window);
  160.  
  161. See the included examples and src-glut/glutCreateWindow.c for inspiration,
  162. and the mesadriver and outputhandler docs.
  163.  
  164.  
  165.  
  166. GLUT
  167. ====
  168.  
  169. Having a Mesa library is all fine and dandy, but most Mesa and OpenGL
  170. examples use the GL Utility Toolkit (GLUT) by Mark Kilgard. So the obvious
  171. answer is: we need a port of GLUT.
  172.  
  173. Having looked at the GLUT source code, this is easier said than done. It
  174. is highly X11-centric, with a Windows port mixed in. I thought about it,
  175. but in the end I decided to do a from-scratch GLUT look-alike
  176. implementation. It can be found in amiga/src-glut.
  177.  
  178. At present, most of the most-commonly used functions are implemented. No
  179. guarantee that they behave identically to the official GLUT distribution,
  180. but most of the redbook examples seem to work OK.
  181.  
  182.  
  183. Using GLUT
  184. ----------
  185.  
  186. when compiling a GLUT program, make sure you link with GLUT.LIB and
  187. Mesa.LIB. These will open the libraries for you. If you want to open the
  188. GLUT library yourself, you must remember to tell GLUT which mesamain base
  189. and mesadriver base to use by calling glutAssociateGL(). These bases
  190. should be the same ones the application is using.
  191.  
  192. When run, a glut program will by default let the output handler open a
  193. window. If told top open a window itself, GLUT will try to open a window
  194. on a public screen named Mesa, or the one specified by the pubscreen
  195. argument. Use one of the zillion pubscreen managers available on AmiNet to
  196. set up a public screen.
  197.  
  198. GLUT Menus
  199. ..........
  200. The GLUT menus use the usual Amiga menu system. Instead of having a menu
  201. associated with a mouse button, there is a "Left Menu", "Middle Menu", and
  202. "Right Menu" menu.
  203. As the Amiga menu system only supports up to one level of sub-menus, any
  204. sub-sub-menus (and sub-sub-sub-menus and sub-sub-sub-sub-menus and ...)
  205. will be changed to a sub-menu after the parent.
  206.  
  207. GLUT mouse buttons
  208. ..................
  209. As the right mouse button is tied up with menus, middle an